Windows Expert/Windows Expert.iso/network/helldivr.zip/HSEND.DOC

Text File | 1992-08-16 | 15KB | 334 lines

            Helldiver Send Mail/News Interface

                   Version 1.03

              Copyright (C) 1991-1992 Rhys Weatherley

1. INTRODUCTION.

This document describes how to use the Helldiver Send program HSEND.EXE to
send mail and news under Waffle.  The Helldiver Newsreader executes this DOS
program as its final mailing and posting stage.  In effect, Helldiver Send
provides an abstract interface for sending mail and news that is independent
of any particluar news/mail system.  It is intended that other similar programs
will be written in the future by myself or others for other UUCP systems.
Normally the user of a mailer or newsreader would not need to use HSEND.EXE
directly - the mailer or newsreader would invoke HSEND.EXE itself.

Currently Helldiver Send supports Waffle 1.64 and 1.65.

Because this program could prove useful to other people's projects, HSEND.EXE
may be distributed free of charge with your own programs as long as either
this documentation file is included verbatim, or the following copyright and
warranty message pertaining to Helldiver Send is included in your own
documentation:

-------------------------------------------------------------------------------
Helldiver Send, Copyright (C) 1991-1992 Rhys Weatherley, [e-mail]

Permission to use, copy, and distribute this material for any purpose
and without fee is hereby granted, provided that the above copyright notice
and this permission notice appear in all copies, and that the name of Rhys
Weatherley not be used in advertising or publicity pertaining to this material
without specific, prior written permission.  RHYS WEATHERLEY MAKES NO
REPRESENTATIONS ABOUT THE ACCURACY OR SUITABILITY OF THIS MATERIAL FOR ANY
PURPOSE.  IT IS PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.
-------------------------------------------------------------------------------

Please contact me via e-mail at [e-mail] if you have any further
queries about Helldiver Send, or would like the latest version.

Other people are welcome to write Helldiver Send clones conforming to this
specification for Waffle, or for other mail/news packages.  Please contact me
if you wish to extend this specification in any way so everyone's programs can
keep the same interface.  To be conformant to this specification, both the
command-line and control file formats described below must be adhered to.

2. COMMAND-LINE USAGE.

Helldiver Send has the following two command-line usage alternatives:

    hsend (filename|-) command
    hsend control-file

In the first case, the filename specified in the first argument (standard
input if "-") is fed to the command specified by the remaining arguments as
standard input.  Usually the command has one of the forms:

    rmail addresss ...
    rnews

This usage requires that the message be fully formatted already, complete
with From:, Message-Id: lines, etc.  It is not recommended that new programs
calling Helldiver Send use this option.  It is provided exclusively for
backwards-compatibilty with an earlier version of Helldiver Send that had a
limited audience.  The current version runs Waffle's RMAIL.EXE or RNEWS.EXE
programs which must be on the PATH.  Conformant implementations may interpret
"rmail" and "rnews" (in either case) as invoking the local mail and news
transmission facilities, whatever they may be.

The second usage above is the recommended usage for all callers of Helldiver
Send and conformant clones.  The single argument specifies a control file
containing commands telling Helldiver Send how to transmit a mail or news
message.  The next section describes the legal commands.  An extensive,
albeit atypical, example control file follows:

    File: f:\waffle\temp\msgaaba.tmp
    From: rhys
    From-name: Rhys Weatherley
    Newsgroups: news.groups,news.admin
    Mod-newsgroup: comp.archives [e-mail]
    Mod-newsgroup: comp.risks [e-mail]
    Local-newsgroup: 0.admin d:\news\local\0\admin
    Local-newsgroup: 0.talk d:\news\local\0\talk
    Followup-To: news.groups,news.admin
    Followup-To-local: 0.talk
    To: peter
    Cc: paul
    Cc: mary
    Bcc: rhys
    X-Mailer: Helldiver 1.04 (Waffle 1.64)
    Append: f:\waffle\user\rhys\outbox
    Sig: f:\waffle\user\rhys\sig
    Lines: 40
    Ref-groups: news.groups,news.admin,comp.archives,comp.risks
    Distribution: aus
    Dead-letters: f:\waffle\user\rhys\dead
    Software: Waffle 1.64
    Approved-for: [e-mail] (John Citizen)
    Expires: 76757576
    Control: cancel <.....>
    Ignore: Newsgroup
    Ignore: Crossposted-To
    Ignore: Follow
    Tempdir: f:\waffle\temp
    Delete: no
    Delete-control: no
    Subject: PROGRAM.ZIP - a little useless program (Part 02/05)
    Reply-To: [e-mail]

3. CONTROL FILE COMMANDS.

This section describes the commands that may be specified in a control file.
The ordering of command lines is not important.  More than one message can
be specified in the same control file by separating the relevant sections with
a line containing a single "-" character.  Unknown commands are ignored.

The meaning of each section is as follows: if there is a "To:", "Cc:" or "Bcc:"
line, then a mail message is sent.  If there is a "Newsgroups" line, then a
news message is posted.  If there is a "Local-newsgroup" line is specified,
then a message is posted to a local newsgroup.  If there is a "Mod-newsgroup"
line, then a mail message is sent for a moderated newsgroup.  Each of the
above may be mixed to send more than one message at once.  Helldiver Send
avoids sending the final messages with a mixture of normal, local and
moderated groups.  In particular, a final message posted to a normal
newsgroup doesn't contain any local or moderated newsgroup names, and a
final message posted to a moderated newsgroup must not contain any other
newsgroup names, including other moderated groups.

It is unclear as to whether Helldiver Send's behaviour with a mixture of
normal, local, and moderated groups is consistent with current USENET
practice in all cases.  This may change in future versions, but conformant
implementations must still understand the "Newsgroups", "Local-newsgroup"
and "Mod-newsgroup" control file commands.

If an RFC-822 or RFC-1036 compliant header line is specified below, then it
should be removed from the original message file before copying the message
file to the final message.  The input message file specified by the "File:"
command must consist of zero or more header lines, followed by a blank line
and the body of the message.  If a header is implicitly specified by one of
the commands below, it doesn't need to be included in the original message,
though it can be: it will just be ignored.

Append:
    If present, this command specifies a file to append the initial message
    (specified by "File:") to.  This is useful if a user has requested that
    all their messages be saved in a file before transmission.

Approved-for:
    If present, this command tells Helldiver Send to use the argument as
    the "From:" line for the final message, and to use the "From:" command
    as the user-id for the user approving the message, and the "Sender:"
    name.  The "Approved:" line always has the form "user@host" where
    "host" is derived externally to Helldiver Send (in the case of Waffle,
    it is specified in the STATIC file).  This is a semi-security measure
    to ensure that e-mail names of user's on a different site may not be
    inserted into the "Approved:" line.  Helldiver Send automatically
    removes any "Approved:" lines in the original message file to prevent
    bypassing this security feature.

Bcc:
    Specify the e-mail address of a blind carbon-copy recipient of a
    mail message.  Only one recipient may be specified on the line,
    but more than one "Bcc:" line may be given.

Cc:
    Specify the e-mail address of a carbon-copy recipient of a mail
    message.  Only one recipient may be specified on the line, but
    more than one "Cc:" line may be given.

Control:
    The text of the "Control:" line in the final message.  Note that
    supporting this command can be a _big_ USENET security risk.  It is
    recommended that friendly front-end user interfaces not use this
    command, except maybe for the cancellation of a user's articles.
    Conformant Helldiver Send clones may wish to inhibit this command
    or restrict the control messages that can be generated using it.
    Ultimately it is not possible to stop a system administrator
    generating bogus control messages by directly talking to RNEWS,
    but other users should be restricted from its use.

Dead-letters:
    The name of a file to append messages to that could not be delivered
    for any reason.  The Helldiver Newsreader uses the file "DEAD" in the
    user's home directory for this purpose.  If this command is not
    present, dead letters are merely discarded.

Delete:
    If present, it indicates if the message file specified by "File:"
    should NOT be deleted after message delivery.  The default is to
    delete the file.  The argument should be "no" in lower case for
    upwards compatibility with future Helldiver Send versions.  Currently
    the argument is ignored, and file is deleted if this command is
    not present.

Delete-control:
    Similar to "Delete:", but indicates if the control file should be
    deleted after delivering all messages.  This command must occur in
    the first section if there is more than one separated by "-" lines.
    It is recommended that callers of Helldiver Send not specify "Delete"
    or "Delete-control" but arrange for temporary files to be used for
    both the message and control files.  Thus, a single call on Helldiver
    Send can stand-alone, with the calling program not needing to do
    any clean-up afterwards.  This is important in environments like
    Microsoft Windows where it is difficult to detect when a child process
    (like running Helldiver Send to send a message) has terminated and
    clean up the temporary files in the parent: all clean-ups are done
    in Helldiver Send itself.

Distribution:
    A comma-separated list of USENET distributions to place into the
    final message's "Distribution:" line.

Expires:
    An expiry date in Unix datetime format (i.e. the number of seconds
    since 1 Jan 1970).

File:
    Specifies the name of the file containing the message.  The header is
    separated from the body by a single blank line.  The header may
    contain some header fields that are automatically generated by other
    control file commands, which are ignored when the final message is
    generated.

Followup-To:
    Specifies a comma-separated list of newsgroups to enter into the
    final message's "Followup-To:" line.

Followup-To-local:
    Specifies a comma-separated list of local newsgroups to enter into
    the "Followup-To:" line (in addition to any "Followup-To" groups) for
    messages posted to local newsgroups.

From:
    Specify the user-id of the user the message is from.  If the
    "Approved-for:" line is also present, this specifies the user-id of
    the user approving the message and "Approved-for:" gives the text
    of the final message's "From:" line.

From-name:
    Real name of the user to be inserted into the "From:" line of the
    final message.  The final "From:" line will have the form
    "user@host (real name)" or "real name <user@host>" depending on
    the implementation.  Helldiver Send uses the first form.  Note that
    the supplied real name may contain unmatched parentheses or angle
    brackets, so a conformant implementation should drop or re-match
    unmatched pairs.  Matched pairs should still be copied to the
    final message though.

Ignore:
    The name of a header field to ignore when generating the final
    message.  i.e. if the header field appears in the original message
    file, then that line will be removed.

Lines:
    Number of lines in the body of the message.  If this command is not
    present, then no "Lines:" header is inserted into the final message.
    Note the comments for the "Sig:" command when using this command.

Local-newsgroup:
    Name of a local newsgroup and the corresponding spool directory.  It
    is assumed that the article is to be stored into the directory as a
    numbered file, and no other processing is required.  On some systems,
    "Newsgroups:" could be used instead of "Local-newsgroup:".  This
    is possible under Waffle, but since RNEWS.EXE is executed, then the
    FEEDS file must be edited to stop local newsgroups being fed to other
    sites.  Note that no checking is done to see if local newsgroups in
    Waffle have overflowed the "/keep" setting.

Mailer-ident:
    A short string of characters that can be inserted into the final
    message's "Message-Id:" field if the program desires to.  The default
    string is an empty string.  For example, the Helldiver Newsreader
    sets this command to "hxyyh" where "x.yy" is the current newsreader
    version, so that Message-Id's have the form "<ABCDEFhxyyh@host>".
    Use of this command can help isolate software versions that generate
    invalid news and mail messages by inspecting the Message-Id.  It is
    not necessary that all conformant implementations use this command.

Mod-newsgroup:
    Name of a moderated newsgroup and the e-mail address to send the
    posting to.

Newsgroups:
    A comma-separated list of newsgroups to post the message to.

Ref-groups:
    If present, then the text of this line is output as the "Newsgroups:"
    line in any mail messages.  It is intended to be used for replies to
    news postings so that the newsgroups appear in the final reply.

Reply-To:
    A fully qualified e-mail address to be inserted into the "Reply-To:"
    line of the final message.

Sig:
    If present, specifies the name of a file to be appended to the final
    message as the user's signature.  Note that if the "Lines:" option
    is also present, then the lines of the signature may not be included
    in the final count, so it is usually better to append the signature
    in the originating program if a "Lines:" header is desired.

Software:
    The name of the software to use for mailing or posting the final
    messages.  At present, Helldiver Send recognises "Waffle 1.64" and
    "Waffle 1.65" in this command as indicating that Waffle 1.64 (or 1.65)
    should be used for sending mail and news.  Contact [e-mail]
    for details on other identifiers, and for registering your own
    identifiers.  If "Software:" is not recognised, then the program
    can either ignore or continue to process the message - this behaviour
    is not defined by this specification.

Subject:
    If present, then it indicates a new subject to be used to replace the
    subject in the original message.  This is convenient for indicating
    the part number for multi-part messages by overriding the user's
    entered subject for each of the parts.

Tempdir:
    This command is mandatory and specifies a directory that temporary
    files can be created in.

To:
    Specify the e-mail address of a recipient of a mail message.  Only
    one recipient may be specified on the line, but more than one "To:"
    line may be given.

X-Mailer:

    An optional comment line.  The contents of this line are copied into
    an "X-Mailer:" line in the final message.  Usually this is the name
    and version of the program calling Helldiver Send.

Please contact the author at [e-mail] if you have any further queries.